The source code for this FORTH assembler was written by William F. Ragsdale and appeared in Dr. Dobb's Journal, September 1981, PP.12-24. The code generation words and tables were modified to permit 65C02 opcodes by John B. Matthesws. For each word, any expected parameters are shown with the top of the stack to the right; three dashes specify the execution point followed by any stack results.
The FORTH assembler takes some getting used to. It is not a general purpose Apple/6502 assembler, rather it is designed specifically to assemble code into the FORTH dictionary. The format for assembly code definitions is CODE <instructions> END-CODE. The format for instructions is OPERAND ADDRESS-MODE OPCODE,. Thus 2 # LDA, loads the accumulator with the value 2. Notice that opcodes end in a comma to suggest a logical grouping corresponding to one line of conventional assembly language. Since there are structured conditional branching words ( IF, THEN, ELSE, etc.) there is no facility for labels. Think of these words as macros.
On entry to an assembled CODE definition, the A register is indeterminate, the Y register is 0, and the X register points to the top of the parameter stack. The parameter stack can be accessed using the indexed X addressing mode (see BOT, SEC, and TOS). The return stack can be accessed similarly (see RP)). The location XSAVE is a convenient place to store the X register while it is used for something else. All definitions shouls return to the FORTH address interpreter (see NEXT).
!OP - Procedure used by MPU to build an opcode from TBL and MODE.
# - Specify immediate addressing mode for the next opcode.
) - Specify indirect addressing mode for the next opcode.
)Y - Specify indirect indexed addressing mode for the next opcode.
,X - Specify indexed X addressing mode for the next opcode.
,Y - Specify indexed Y addressing mode for the next opcode.
X) - Specify indexed indirect addressing mode for the next opcode.
.A - Specify accumulator addressing mode for the next opcode.
0< - --- CC (assembling) Specify that the following conditional will branch based on the processor status bit being negative (N=1). The flag CC is left at assembly time; there is no runtime stack effect.
0= - --- CC (assembling) Specify that the following conditional will branch based on the processor status bit being equal to zero (Z=1). The flag CC is left at assembly time; there is no runtime stack effect.
ASSEMBLER - Make ASSEMBLER the CONTEXT vocabulary. It will be searched first when the input stream is interpreted.
;CODE - Used in the form : <name> ... ;CODE <assembly code> END-CODE to stop compilation and terminate a new defining word <name>. It then sets the CONTEXT vocabulary to ASSEMBLER, assembling to machine code the following assembly mnemonics. An existing defining word, such as CREATE, must exist in <name> prior to ;CODE. When <name> later executes in the form <name> <namex> the definition <namex> will be created with its execution procedure given by the machine code following ;CODE. That is, when <namex> is executed, the address interpreter jumps to the code following ;CODE.
BAD -- Used by MPU to exit with an address mode error.
BEGIN, - --- ADDR 1 (assembling) --- (runtime) Occurs in a CODE definition in the form BEGIN, ... CC UNTIL, At runtime BEGIN marks the start of an assembly sequence repeatedly executed. It serves as the return point for the corresponding until,. When reaching UNTIL, a branch to BEGIN, will occur if the processor status bit given by CC is false; otherwise execution continues ahead. At assembly time BEGIN leaves the dictionary pointer address ADDR and the value 1 for later testing of conditional pairing by UNTIL,.
BOT - --- N (assembling) Used during CODE assembly in the form BOT LDA, or BOT 1+ STA, addresses the top of the parameter stack (containing the low byte) by selecting the ,X mode and leaving 0. This value may be modified to another byte offset into the parameter stack. BOT must be followed by a multi-mode opcode mnemonic.
CODE - A defining word used in the form CODE <name> ... END-CODE to create a dictionary entry for <name> in the CURRENT vocabulary. <name>'s code field contains the address of its parameter field. When <name> is later executed, the machine code in this parameter field will execute. The CONTEXT vocabulary is made ASSEMBLER to make available the opcode mnemonics.
CPU - N --- (defining) An assembler defining word used to create assembler mnemonics that have only one addressing mode: EA CPU NOP, creates the word NOP, with its opcode EA as a parameter. When NOP, later executes it assmbles EA as a one byte opcode.
CS - --- CC (assembling) Specify that the following conditional will branch based on the processor carry being set (C=1). The flag CC is left at assembly time. No runtime effect.
ELSE, - --- (runtime) ADDR1 2 --- ADDR2 2 (assembly) Occurs within a CODE definition in the form CC IF, <true> ELSE, <false> THEN, At runtime, if the condition code specified by CC is false, execution will skip to the machine code following ELSE,. At assembly time ELSE assembles a forward jump to just after THEN, and resolves a pending forward branch from IF. The constants are used for error checking of conditional pairing.
END-CODE - An error check word marking the end of a CODE definition. Successful execution to and including END-CODE will SMUDGE the most recent CURRENT vocabulary definition, making it available for execution. END-CODE also exits the assembler making CONTEXT the same as CURRENT. This word previously was named C;.
IF, - CC --- ADDR 2 (assembly) --- ADDR 2 (assembly) Occurs within a CODE definition in the form CC IF, <true> ELSE, <false> THEN, At runtime IF, branches based on the condition code CC (0< or 0= or CS). If the specified processor status is true, execution continues ahead, otherwise branching occurs to just after THEN, or ELSE,. At ELSE, execution resumes at the corresponding THEN,. When assembling IF, creates an unresolved forward branch based on the condition code CC, and leaves ADDR and 2 for resolution of the branch by the corresponding ELSE, or THEN,. Conditionals may be nested.
IP - --- ADDR (assembling) Used in a CODE definition in the form IP STA, or IP )Y LDA, IP is a constant which leaves the address of the pointer to the next FORTH execution address in the colon definition being interpreted. At runtime NEXT moves IP to W, increments IP by two, and jumps indirectly through W. Therefore IP points just after the execution address being interpreted. If an inline data structure has been compiled (e.g. a character string), indexing ahead by IP can access this data.
MPU - N1 N2 --- (defining) An assembler defining word used to create assembler mnemonics that have multiple address modes. For example, 1CEE 0060 M/CPU ADC, creates the word ADC, with two parameters. When ADC, later executes it uses these parameters, along with stack values and the contents of MODE, to calculate and assemble the correct opcode and operand. A short address mode will be generated if possible.
MEM - Used within the assembler to set MODE to direct memory addressing. This mode is set after every opcode generated.
MODE - A variable used within the assembler which holds a flag indicating the addressing mode of the opcode being generated.
N - Used in a CODE definition as in the form N 1 - STA, or N 2+ )Y ADC, It is a constant which leaves the address of a 9 byte workspace in zero page. Within a single CODE definition you can use N-1 thru N+8. See SETUP.
NEXT - A constant which leaves the machine address of the FORTH address interpreter. All CODE definitions must return execution to NEXT, or code that returns to NEXT (ie. PUSH, POP, PUT, POPTWO). See IP.
NOT - CC1 --- CC2 (assembling) When assembling, reverse the condition code for the following conditional. For example, 0= NOT IF, <true part> THEN, will branch based on 'not equal to zero' (i.e. zero flag clear).
POP - --- ADDR (assembling) N --- (runtime) A constant which leaves (during assembly) the machine address of the routine which at runtime will pop a 16-bit value from the parameter stack and continue interpretation.
POPTWO - --- ADDR (assembling) N1 N2 --- (runtime) Same as POP but has the runtime action of popping top two 16-bit numbers off the stack.
PUSH - --- ADDR (assembling) --- N (runtime) A constant which during assembly leaves the machine address of the outine which at runtime will push the accumulator contents (as highorder byte) and top of 6502 return stack (as loworder byte) to FORTH parameter STACK. For example, to push $1234 to the parameter stack and return to the interpreter, CODE 34 # LDA, PHA, 12 # LDA, PUSH JMP,.
PUT - --- ADDR (assembling) N1 --- N2 (runtime) A constant which during assembly leaves the machine addressof the routine which at runtime will write the accumulator contents (as high order byte) and top of 6502 return stack (as low order byte) over the current top of the forth data stack. In other words, PUSH pushes the value onto the stack, PUT overwrites the current top of stack with the value.
RP) - --- (assembly) Used in a CODE definition in the form RP) LDA, or RP) 3+ STA, Address the top byte of the 6502 return stack by automatically selecting the ,X mode and leaving N=$101. N may be modified to another byte offset. Before operating on the return stack, the X register must be saved in XSAVE and TSX, must be executed. Before returning to NEXT, the X register must be restored from XSAVE.
SEC - --- N (assembling) Addresses the low byte of the second 16-bit parameter stack value (third byte on the stack). See BOT and TOS.
SETUP - A constant the leaves the address of a routine that unpacks one or more 16 bit numbers from the parameter stack into the N area of zero page. On entry the A register contains the number (from 1 to 4) of 16 bit numbers to unpack. This value is multiplied by 2 and stored at N-1. These 16 bit values are then copied into N, N+2, etc. The stack pointer (in X) is unchanged and Y is set to zero.
TBL - --- ADDR (assembling) An array used within the assembler which holds bit patterns for allowable addressing modes.
THEN, - ADDR 2 --- (assembling) At runtime THEN, marks the conclusion of a conditional structure. Executon of either the true part or the false part resumes following THEN,. When assembling, ADDR and 2 are used to resolve the pending forward branch to THEN,. THEN, is not invoked at runtime.
TOS - --- N (assembling) Identical to BOT but more mnemonic.
UNTIL, - ADDR 1 CC --- (assembling) Occurs in a CODE definition in the form BEGIN, ... CC UNTIL, At runtime UNTIL, controls the conditional branching back to BEGIN,. If the processor status bit specified by CC is false, execution returns to BEGIN,. If it is true, execution continues. At assembly time UNTIL, assembles a conditional relative branch to ADDR based on the condition code CC. The number 1 is used for error checking.
UP - Used in a CODE definition n the form UP LDA, or UP )Y STA, UP is a constant which at assembly time leaves the address of the pointer to the base of the user area. e.g. HEX 12 # LDY, UP )Y LDA, loads the low byte of the sixth user variable.
VAL - ADDR --- ADDR F For a given opcode, returns true if the current MODE is allowed; used by MPU.
